Cloudflare Workers(Rust)からKVを使うチュートリアルをやってみた #Cloudflare

どうも！オペ部西村祐二です。

この記事は「Cloudflare のアドベントカレンダー」の4日目の記事です。

以前、下記のようなブログを書きました。そこからCloudflareのサービスに興味がでてきましたので今回、Cloudflare Workers(Rust)からCloudflare Workers KVを使うチュートリアルをやってみました。

今回、やってみたチュートリアルは下記になります。

Use Workers KV directly from Rust · Cloudflare Workers docs

Cloudflare Workers KVとは

Cloudflareのアプリケーション向けサーバーレス Key-Value ストレージです。

Cloudflare Workers KVは、Cloudflareのグローバルネットワーク内にあるすべてのデータセンターで、セキュアな低レイテンシーKey-Value Storeへのアクセスを提供。

Cloudflare Workers KV｜サーバーレスコンピューティング | Cloudflare

やってみる

環境

• MacOS: 10.15.7

• Rust: v1.58.0-nightly

• Wrangler: 1.19.5

事前準備

• warnglerをインストール

wranglerというCLIをインストールしてCloudflareの環境を操作できるようにしておいてください。

詳細は下記参考サイトを確認ください。

cloudflare/wrangler: ? wrangle your Cloudflare Workers

Get started guide · Cloudflare Workers docs

雛形プロジェクトを作成

wranglerを使って雛形プロジェクトを作成します。

worker-rsを使用したテンプレートを指定します。

worker-rsはWebAssembly経由でRustで記述したプログラムをCloudflare Workersで動かすためのクレート（ライブラリ）です。

$ wrangler generate workers-kv-from-rust https://github.com/cloudflare/rustwasm-worker-template/
$ cd workers-kv-from-rust
$ git add -A
$ git commit -m 'Initial commit'

KV namespaceを作成

wranglerをつかって「KV_FROM_RUST」を指定し、namespaceを作成します。

プロジェクト名と指定した値を連結した「workers-kv-from-rust-KV_FROM_RUST」というnamespaceが作成されます。

❯ wrangler kv:namespace create "KV_FROM_RUST"
?  Creating namespace with title "workers-kv-from-rust-KV_FROM_RUST"
✨  Success!
Add the following to your configuration file:
kv_namespaces = [
	 { binding = "KV_FROM_RUST", id = "xxxxxxxxxxxxxxxxxxx" }

また、--previewをつけるとローカルから実行するときに参照されるKV namespaceを作成してくれます。

❯ wrangler kv:namespace create "KV_FROM_RUST" --preview
?  Creating namespace with title "workers-kv-from-rust-KV_FROM_RUST_preview"
✨  Success!
Add the following to your configuration file:
kv_namespaces = [
	 { binding = "KV_FROM_RUST", preview_id = "xxxxxxxxxxxxxx" }
]

webコンソールを確認するとちゃんと作成されていることがわかります。

KV namespaceをバインドさせる

KV namespace作成時に生成されたidをwrangler.tomlファイルに追加します。

.
.
.
kv_namespaces = [
  { binding = "KV_FROM_RUST", preview_id = "xxxxxxxxxxxxx", id = "xxxxxxxxxx" }
]
.
.
.

KV namespaceにアクセスするための下処理追加

JS側では変数KV_FROM_RUSTとして、作成したKV namespaceにアクセスします。Rustの名前空間から読み取りまたは書き込みを行うには、オブジェクト全体をRustハンドラー関数に渡す必要があります。

$ mkdir worker
$ cd worker
$ touch worker.js

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

const { handle } = wasm_bindgen;
const instance =  wasm_bindgen(wasm);
/**
 * Fetch and log a request
 * @param {Request} request
 */
async function handleRequest(request) {
  await instance;

  return await handle(KV_FROM_RUST, request);
}

このチュートリアルでは、Rust側で可能な限り多くの処理を実行し、リクエストを直接wasmハンドラーに渡して、wasmハンドラーが応答を作成して返します。

リクエストとレスポンスの処理をJavaScript側で維持するテンプレートとは異なることに注意してください。

Rust側でなるべく処理を寄せるために、web-sysをRust依存関係の1つとして宣言し、Request、Response、およびResponseInitを明示的に有効にします。（UrlおよびUrlSearchParams機能はこのチュートリアルの後半で使用されます）。

.
.
.
[dependencies.web-sys]
version = "0.3"
features = [
    'Request',
    'Response',
    'ResponseInit',
    'Url',
    'UrlSearchParams',
]

下記のように記述することでRustのRequest、Responseを使用して、常に200OKステータスで応答するシンプルなハンドラーを作成できます。

extern crate cfg_if;
extern crate wasm_bindgen;

mod utils;

use cfg_if::cfg_if;
use wasm_bindgen::{JsCast, prelude::*};
use web_sys::{Request, Response, ResponseInit};

cfg_if! {
    // When the `wee_alloc` feature is enabled, use `wee_alloc` as the global
    // allocator.
    if #[cfg(feature = "wee_alloc")] {
        extern crate wee_alloc;
        #[global_allocator]
        static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
    }
}

#[wasm_bindgen]
pub fn handle(kv: JsValue, req: JsValue) -> Result<Response, JsValue> {
    let req: Request = req.dyn_into()?;
    let mut init = ResponseInit::new();
    init.status(200);
    Response::new_with_opt_str_and_init(None, &init)
}

wasm_bindgenを使用してKVにバインドする

先程のsrc/lib.rsをベースに発展させていきます。

KV APIはJavaScriptのpromiseを返すため、依存関係としてwasm-bindgen-futuresとjs-sysを追加する必要があります。

[dependencies]
cfg-if = "0.1.2"
wasm-bindgen = "=0.2.73"
wasm-bindgen-futures = "0.4"
js-sys = "0.3"

wasm_bindgenを使用して型バインディングを作成してKVオブジェクトにアクセスするようにしたコードが下記になります。

.
.
.
#[wasm_bindgen]
pub fn handle(kv: WorkersKvJs, req: JsValue) -> Result<Response, JsValue> {
    let req: Request = req.dyn_into()?;
    let mut init = ResponseInit::new();
    init.status(200);
    Response::new_with_opt_str_and_init(None, &init)
}

#[wasm_bindgen]
extern "C" {
    pub type WorkersKvJs;

    #[wasm_bindgen(structural, method, catch)]
    pub async fn put(
        this: &WorkersKvJs,
        k: JsValue,
        v: JsValue,
        options: JsValue,
    ) -> Result<JsValue, JsValue>;

    #[wasm_bindgen(structural, method, catch)]
    pub async fn get(
        this: &WorkersKvJs,
        key: JsValue,
        options: JsValue,
    ) -> Result<JsValue, JsValue>;
}

KVのラッパーを作成

KVパラメーターをそのまま使用し始めることもできますが、wasm_bindgenによって生成された関数シグネチャはRust内で機能するのが難しい場合があります。より簡単に扱うために、WorkersKvJs型の周りに単純な構造体を作成して、よりRustに適したAPIでラップします。

.
.
.
use js_sys::{ArrayBuffer, Object, Reflect, Uint8Array};

struct WorkersKv {
    kv: WorkersKvJs,
}

impl WorkersKv {
    async fn put_text(&self, key: &str, value: &str, expiration_ttl: u64) -> Result<(), JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"expirationTtl".into(), &(expiration_ttl as f64).into())?;
        self.kv
            .put(JsValue::from_str(key), value.into(), options.into())
            .await?;
        Ok(())
    }

    async fn put_vec(&self, key: &str, value: &[u8], expiration_ttl: u64) -> Result<(), JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"expirationTtl".into(), &(expiration_ttl as f64).into())?;
        let typed_array = Uint8Array::new_with_length(value.len() as u32);
        typed_array.copy_from(value);
        self.kv
            .put(
                JsValue::from_str(key),
                typed_array.buffer().into(),
                options.into(),
            )
            .await?;
        Ok(())
    }

    async fn get_text(&self, key: &str) -> Result<Option<String>, JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"type".into(), &"text".into())?;
        Ok(self
            .kv
            .get(JsValue::from_str(key), options.into())
            .await?
            .as_string())
    }

    async fn get_vec(&self, key: &str) -> Result<Option<Vec<u8>>, JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"type".into(), &"arrayBuffer".into())?;
        let value = self.kv.get(JsValue::from_str(key), options.into()).await?;
        if value.is_null() {
            Ok(None)
        } else {
            let buffer = ArrayBuffer::from(value);
            let typed_array = Uint8Array::new_with_byte_offset(&buffer, 0);
            let mut v = vec![0; typed_array.length() as usize];
            typed_array.copy_to(v.as_mut_slice());
            Ok(Some(v))
        }
    }
}

上記のラッパーは、KV APIでサポートされているオプションのサブセットのみを利用可能にします。たとえば、putのexpirationTtlの代わりにexpirationや、getのtextやarrayBuffer以外のタイプなど、他のオプションも同様の方法でラップできます。概念的には、ラッパーメソッドはすべてReflect::setを使用して手動でJSオブジェクトを作成し、必要に応じて戻り値を標準のRust型に変換します。

ラッパーを利用する処理を追加

ラッパーを使用してKV namespaceとの間で値を読み書きする準備が整いました。

次の関数は、URLセグメントを使用してKVドキュメントのキー名と値を決定し、PUTリクエストでKVに書き込むハンドラーの例です。たとえば、PUTリクエストを/foo？value=barに送信すると、「bar」値がfooキーに書き込まれます。

さらに、サンプルハンドラーは、GETリクエスト時に、URLパス名をキー名として使用してKVから読み取ります。たとえば、GET /fooリクエストは、fooキーの値があればそれを返します。

.
.
.
#[wasm_bindgen]
pub async fn handle(kv: WorkersKvJs, req: JsValue) -> Result<Response, JsValue> {
    let req: Request = req.dyn_into()?;
    let url = web_sys::Url::new(&req.url())?;
    let pathname = url.pathname();
    let query_params = url.search_params();
    let kv = WorkersKv { kv };
    match req.method().as_str() {
        "GET" => {
            let value = kv.get_text(&pathname).await?.unwrap_or_default();
            let mut init = ResponseInit::new();
            init.status(200);
            Response::new_with_opt_str_and_init(Some(&format!("\"{}\"\n", value)), &init)
        },
        "PUT" => {
            let value = query_params.get("value").unwrap_or_default();
            // set a TTL of 60 seconds:
            kv.put_text(&pathname, &value, 60).await?;
            let mut init = ResponseInit::new();
            init.status(200);
            Response::new_with_opt_str_and_init(None, &init)
        },
        _ => {
            let mut init = ResponseInit::new();
            init.status(400);
            Response::new_with_opt_str_and_init(None, &init)
        }
    }
}

src/lib.rsのコード全体

チュートリアルで紹介されたlib.rsのコードは下記のようになります。

KVにデータをPUTするときにTTL60秒が設定されて保存されるようになっているのでご注意ください。

extern crate cfg_if;
extern crate wasm_bindgen;

mod utils;

use cfg_if::cfg_if;
use js_sys::{ArrayBuffer, Object, Reflect, Uint8Array};
use wasm_bindgen::{prelude::*, JsCast};
use web_sys::{Request, Response, ResponseInit};

cfg_if! {
    // When the `wee_alloc` feature is enabled, use `wee_alloc` as the global
    // allocator.
    if #[cfg(feature = "wee_alloc")] {
        extern crate wee_alloc;
        #[global_allocator]
        static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
    }
}

#[wasm_bindgen]
pub async fn handle(kv: WorkersKvJs, req: JsValue) -> Result<Response, JsValue> {
    let req: Request = req.dyn_into()?;
    let url = web_sys::Url::new(&req.url())?;
    let pathname = url.pathname();
    let query_params = url.search_params();
    let kv = WorkersKv { kv };
    match req.method().as_str() {
        "GET" => {
            let value = kv.get_text(&pathname).await?.unwrap_or_default();
            let mut init = ResponseInit::new();
            init.status(200);
            Response::new_with_opt_str_and_init(Some(&format!("\"{}\"\n", value)), &init)
        }
        "PUT" => {
            let value = query_params.get("value").unwrap_or_default();
            // set a TTL of 60 seconds:
            kv.put_text(&pathname, &value, 60).await?;
            let mut init = ResponseInit::new();
            init.status(200);
            Response::new_with_opt_str_and_init(None, &init)
        }
        _ => {
            let mut init = ResponseInit::new();
            init.status(400);
            Response::new_with_opt_str_and_init(None, &init)
        }
    }
}

#[wasm_bindgen]
extern "C" {
    pub type WorkersKvJs;

    #[wasm_bindgen(structural, method, catch)]
    pub async fn put(
        this: &WorkersKvJs,
        k: JsValue,
        v: JsValue,
        options: JsValue,
    ) -> Result<JsValue, JsValue>;

    #[wasm_bindgen(structural, method, catch)]
    pub async fn get(
        this: &WorkersKvJs,
        key: JsValue,
        options: JsValue,
    ) -> Result<JsValue, JsValue>;
}

struct WorkersKv {
    kv: WorkersKvJs,
}

impl WorkersKv {
    async fn put_text(&self, key: &str, value: &str, expiration_ttl: u64) -> Result<(), JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"expirationTtl".into(), &(expiration_ttl as f64).into())?;
        self.kv
            .put(JsValue::from_str(key), value.into(), options.into())
            .await?;
        Ok(())
    }

    async fn put_vec(&self, key: &str, value: &[u8], expiration_ttl: u64) -> Result<(), JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"expirationTtl".into(), &(expiration_ttl as f64).into())?;
        let typed_array = Uint8Array::new_with_length(value.len() as u32);
        typed_array.copy_from(value);
        self.kv
            .put(
                JsValue::from_str(key),
                typed_array.buffer().into(),
                options.into(),
            )
            .await?;
        Ok(())
    }

    async fn get_text(&self, key: &str) -> Result<Option<String>, JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"type".into(), &"text".into())?;
        Ok(self
            .kv
            .get(JsValue::from_str(key), options.into())
            .await?
            .as_string())
    }

    async fn get_vec(&self, key: &str) -> Result<Option<Vec<u8>>, JsValue> {
        let options = Object::new();
        Reflect::set(&options, &"type".into(), &"arrayBuffer".into())?;
        let value = self.kv.get(JsValue::from_str(key), options.into()).await?;
        if value.is_null() {
            Ok(None)
        } else {
            let buffer = ArrayBuffer::from(value);
            let typed_array = Uint8Array::new_with_byte_offset(&buffer, 0);
            let mut v = vec![0; typed_array.length() as usize];
            typed_array.copy_to(v.as_mut_slice());
            Ok(Some(v))
        }
    }
}

ローカルで動作確認

CLIを使ってローカルサーバを実行してみます。

するとエラーとなってしまいました。

$ wrangler dev
.
.
.
[INFO]: ⬇️  Installing wasm-bindgen...
[INFO]: Optimizing wasm binaries with `wasm-opt`...
[INFO]: Optional fields missing from Cargo.toml: 'description', 'repository', and 'license'. These are not necessary, but recommended
[INFO]: ✨   Done in 1.31s
[INFO]: ?   Your wasm pkg is ready to publish at /Users/nishimura.yuji/study/cloudflare/kv/workers-kv-from-rust/build.
Error: Something went wrong with the request to Cloudflare...
Uncaught SyntaxError: The requested module './index_bg.mjs' does not provide an export named 'fetch'
  at line 2
 [API code: 10021]

エラー修正

wrangler.tomlの2行がjavascriptになっていたので、rustに修正します。

name = "workers-kv-from-rust"
type = "rust"
workers_dev = true
compatibility_date = "2021-12-03"
kv_namespaces = [
.
.
.

再度、ローカルで動作確認

CLIを使ってローカルサーバを実行してみます。

一応エラーが出ずにロールサーバがたちあがりました。いくつか警告がでていますがチュートリアルということで今回は無視して進めます。

$ wrangler dev
.
.
.
[INFO]: ⬇️  Installing wasm-bindgen...
[INFO]: Optimizing wasm binaries with `wasm-opt`...
[INFO]: Optional fields missing from Cargo.toml: 'description', 'repository', and 'license'. These are not necessary, but recommended
[INFO]: ✨   Done in 0.53s
[INFO]: ?   Your wasm pkg is ready to publish at /Users/nishimura.yuji/study/cloudflare/kv/workers-kv-from-rust/pkg.
[WARN]: ⚠️   There's a newer version of wasm-pack available, the new version is: 0.10.1, you are using: 0.10.0. To update, navigate to: https://rustwasm.github.io/wasm-pack/installer/
?  watching "./"
?  Listening on http://127.0.0.1:8787

curlを使って動作確認してみます。

$ curl 'localhost:8787/foo'
""
$ curl -X PUT 'localhost:8787/foo?value=bar'
$ curl 'localhost:8787/foo'
"bar"

問題なく動作しているようです。

また、TTLを60秒で設定しているので、時間が経過するとKVからデータが消えていることも確認できました。

webコンソールから確認してみます。

末尾に「preview」のKV namespaceの中にデータがあることが確認できました。

デプロイ

チュートリアルでは記載はないですが、実際にデプロイして動作確認もしてみます。

下記コマンドで簡単にデプロイできます。

❯ wrangler publish
?  Compiling your project to WebAssembly...
[INFO]: ?  Checking for the Wasm target...
[INFO]: ?  Compiling to Wasm...
[INFO]: ⬇️  Installing wasm-bindgen...
[INFO]: Optimizing wasm binaries with `wasm-opt`...
.
.
.

✨  Build succeeded
✨  Successfully published your script to
 https://<your url>

curlで動作確認してみます。

今度はJSON形式のデータの{"name":"foo","selected":[1,2,3],"flags":{"a":true,"b":false}}を保存します。

jsonをurlにパスに変換する必要があります。

$ curl -X PUT 'https://<your url>/foo2?value=%7B%22name%22%3A%22foo%22%2C%22selected%22%3A%5B1%2C2%2C3%5D%2C%22flags%22%3A%7B%22a%22%3Atrue%2C%22b%22%3Afalse%7D%7D'

$ curl 'https://<your url>/foo2'
"{"name":"foo","selected":[1,2,3],"flags":{"a":true,"b":false}}"

webコンソールからもきちんとデータが保存されていることが確認できます。

また KV namespaceはpreviewがついていないnamespaceに保存されています。

さいごに

Cloudflare Workers(Rust)からCloudflare Workers KVを使うチュートリアルをやってみました。

Cloudflare WorkersがV8を直接実行できる環境ということもあって、RustとWebAssemblyの知識、wasm-bindgenの使い方などの知識が必要となり、なかなかハードルを感じましたがとても楽しく、勉強になるチュートリアルでした。

誰かの参考になれば幸いです。

参考サイト

Rust から WebAssembly にコンパイルする - WebAssembly | MDN

wasm-pack で JS の Promise を await できる非同期 Rust を書いて node.js で動かす - Qiita

fkettelhoit/workers-kv-from-rust: Example Cloudflare Worker that calls Workers KV directly from Rust